<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 7 Configuration Reference (7.0.42) - The LifeCycle Listener Component</title><style type="text/css" media="print">
            .noPrint {display: none;}
            td#mainBody {width: 100%;}
        </style><style type="text/css">
            code {background-color:rgb(224,255,255);padding:0 0.1em;}
            code.attributeName, code.propertyName {background-color:transparent;}
        </style><style type="text/css">
            .wrapped-source code { display: block; background-color: transparent; }
            .wrapped-source div { margin: 0 0 0 1.25em; }
            .wrapped-source p { margin: 0 0 0 1.25em; text-indent: -1.25em; }
        </style><style type="text/css">
            p.notice {
                border: 1px solid rgb(255, 0, 0);
                background-color: rgb(238, 238, 238);
                color: rgb(0, 51, 102);
                padding: 0.5em;
                margin: 1em 2em 1em 1em;
            }
        </style></head><body bgcolor="#ffffff" text="#000000" link="#525D76" alink="#525D76" vlink="#525D76"><table border="0" width="100%" cellspacing="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img src="../images/tomcat.gif" align="right" alt="
    The Apache Tomcat Servlet/JSP Container
  " border="0"></a></td><td><h1><font face="arial,helvetica,sanserif">Apache Tomcat 7</font></h1><font face="arial,helvetica,sanserif">Version 7.0.42, Jul 2 2013</font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img src="../images/asf-logo.gif" align="right" alt="Apache Logo" border="0"></a></td></tr></table><table border="0" width="100%" cellspacing="4"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><tr><!--LEFT SIDE NAVIGATION--><td width="20%" valign="top" nowrap class="noPrint"><p><strong>Links</strong></p><ul><li><a href="../index.html">Docs Home</a></li><li><a href="index.html">Config Ref. Home</a></li><li><a href="http://wiki.apache.org/tomcat/FAQ">FAQ</a></li><li><a href="#comments_section">User Comments</a></li></ul><p><strong>Top Level Elements</strong></p><ul><li><a href="server.html">Server</a></li><li><a href="service.html">Service</a></li></ul><p><strong>Executors</strong></p><ul><li><a href="executor.html">Executor</a></li></ul><p><strong>Connectors</strong></p><ul><li><a href="http.html">HTTP</a></li><li><a href="ajp.html">AJP</a></li></ul><p><strong>Containers</strong></p><ul><li><a href="context.html">Context</a></li><li><a href="engine.html">Engine</a></li><li><a href="host.html">Host</a></li><li><a href="cluster.html">Cluster</a></li></ul><p><strong>Nested Components</strong></p><ul><li><a href="globalresources.html">Global Resources</a></li><li><a href="jar-scanner.html">JarScanner</a></li><li><a href="listeners.html">Listeners</a></li><li><a href="loader.html">Loader</a></li><li><a href="manager.html">Manager</a></li><li><a href="realm.html">Realm</a></li><li><a href="resources.html">Resources</a></li><li><a href="valve.html">Valve</a></li></ul><p><strong>Cluster Elements</strong></p><ul><li><a href="cluster.html">Cluster</a></li><li><a href="cluster-manager.html">Manager</a></li><li><a href="cluster-channel.html">Channel</a></li><li><a href="cluster-membership.html">Channel/Membership</a></li><li><a href="cluster-sender.html">Channel/Sender</a></li><li><a href="cluster-receiver.html">Channel/Receiver</a></li><li><a href="cluster-interceptor.html">Channel/Interceptor</a></li><li><a href="cluster-valve.html">Valve</a></li><li><a href="cluster-deployer.html">Deployer</a></li><li><a href="cluster-listener.html">ClusterListener</a></li></ul><p><strong>Other</strong></p><ul><li><a href="filter.html">Filter</a></li><li><a href="systemprops.html">System properties</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td width="80%" valign="top" align="left" id="mainBody"><h1>The LifeCycle Listener Component</h1><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>
<ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Attributes">Attributes</a><ol><li><a href="#Common_Attributes">Common Attributes</a></li></ol></li><li><a href="#Nested_Components">Nested Components</a></li><li><a href="#Standard_Implementations">Standard Implementations</a><ol><li><a href="#APR_Lifecycle_Listener_-_org.apache.catalina.core.AprLifecycleListener">APR Lifecycle Listener - org.apache.catalina.core.AprLifecycleListener</a></li><li><a href="#Jasper_Listener_-_org.apache.catalina.core.JasperListener">Jasper Listener - org.apache.catalina.core.JasperListener</a></li><li><a href="#Global_Resources_Lifecycle_Listener_-_org.apache.catalina.mbeans.GlobalResourcesLifecycleListener">Global Resources Lifecycle Listener - org.apache.catalina.mbeans.GlobalResourcesLifecycleListener</a></li><li><a href="#JRE_Memory_Leak_Prevention_Listener_-_org.apache.catalina.core.JreMemoryLeakPreventionListener">JRE Memory Leak Prevention Listener - org.apache.catalina.core.JreMemoryLeakPreventionListener</a></li><li><a href="#Security_Lifecycle_Listener_-_org.apache.catalina.security.SecurityListener">Security Lifecycle Listener - org.apache.catalina.security.SecurityListener</a></li><li><a href="#ThreadLocal_Leak_Prevention_Listener_-_org.apache.catalina.core.ThreadLocalLeakPreventionListener">ThreadLocal Leak Prevention Listener - org.apache.catalina.core.ThreadLocalLeakPreventionListener</a></li><li><a href="#UserConfig_-_org.apache.catalina.startup.UserConfig">UserConfig - org.apache.catalina.startup.UserConfig</a></li></ol></li><li><a href="#Additional_Implementations">Additional Implementations</a><ol><li><a href="#JMX_Remote_Lifecycle_Listener_-_org.apache.catalina.mbeans.JmxRemoteLifecycleListener">JMX Remote Lifecycle Listener - org.apache.catalina.mbeans.JmxRemoteLifecycleListener</a></li></ol></li></ul>
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>

  <p>A <strong>Listener</strong> element defines a component that performs
  actions when specific events occur, usually Tomcat starting or Tomcat
  stopping.</p>

  <p>Listeners may be nested inside a <a href="server.html">Server</a>,
  <a href="engine.html">Engine</a>, <a href="host.html">Host</a> or
  <a href="context.html">Context</a>. Some Listeners are only intended to be
  nested inside specific elements. These constraints are noted in the
  documentation below.</p>

</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Attributes"><strong>Attributes</strong></a></font></td></tr><tr><td><blockquote>

  <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Common Attributes"><!--()--></a><a name="Common_Attributes"><strong>Common Attributes</strong></a></font></td></tr><tr><td><blockquote>

    <p>All implementations of <strong>Listener</strong>
    support the following attributes:</p>

    <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><strong><code class="attributeName">className</code></strong></td><td align="left" valign="center">
        <p>Java class name of the implementation to use. This class must
        implement the <code>org.apache.catalina.LifecycleListener</code>
        interface.</p>
      </td></tr></table>

  </blockquote></td></tr></table>

</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Nested Components"><!--()--></a><a name="Nested_Components"><strong>Nested Components</strong></a></font></td></tr><tr><td><blockquote>

  <p>No element may be nested inside a <strong>Listener</strong>.</p>

</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Standard Implementations"><!--()--></a><a name="Standard_Implementations"><strong>Standard Implementations</strong></a></font></td></tr><tr><td><blockquote>

  <p>Unlike most Catalina components, there are several standard
  <strong>Listener</strong> implementations available.  As a result,
  the <code>className</code> attribute MUST be used to select the
  implementation you wish to use.</p>

  <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="APR Lifecycle Listener - org.apache.catalina.core.AprLifecycleListener"><!--()--></a><a name="APR_Lifecycle_Listener_-_org.apache.catalina.core.AprLifecycleListener"><strong>APR Lifecycle Listener - org.apache.catalina.core.AprLifecycleListener</strong></a></font></td></tr><tr><td><blockquote>

    <p>The <strong>APR Lifecycle Listener</strong> checks for the presence of
    the APR/native library and loads the library if it is present. For more
    information see the <a href="../apr.html">APR/native guide</a>.</p>

    <p>This listener must only be nested within <a href="server.html">Server</a>
    elements.</p>

    <p>The following additional attributes are supported by the <strong>APR
    Lifecycle Listener</strong>:</p>

    <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code class="attributeName">SSLEngine</code></td><td align="left" valign="center">
        <p>Name of the SSLEngine to use. <code>off</code>: do not use SSL,
        <code>on</code>: use SSL but no specific ENGINE.</p>
        <p>The default value is <b>on</b>. This initializes the
        native SSL engine, which must be enabled in the APR/native connector by
        the use of the <code>SSLEnabled</code> attribute.</p>
        <p>See the <a href="http://www.openssl.org/">Official OpenSSL website</a>
        for more details on supported SSL hardware engines and manufacturers.
        </p>
      </td></tr><tr><td align="left" valign="center"><code class="attributeName">SSLRandomSeed</code></td><td align="left" valign="center">
        <p>Entropy source used to seed the SSLEngine's PRNG. The default value
        is <code>builtin</code>. On development systems, you may want to set
        this to <code>/dev/urandom</code> to allow quicker start times.</p>
      </td></tr><tr><td align="left" valign="center"><code class="attributeName">FIPSMode</code></td><td align="left" valign="center">
        <p>Set to <code>on</code> to instruct OpenSSL to go into FIPS mode.
        FIPS mode <em>requires you to have a FIPS-capable OpenSSL library which
        you must build yourself</em>.
        FIPS mode also requires Tomcat native library version 1.1.23 or later,
        which <em>must be built against the FIPS-compatible OpenSSL</em> library.
        If this attribute is "on", <b>SSLEngine</b> must be enabled as well.
        The default value is <code>off</code>.</p>
      </td></tr></table>

  </blockquote></td></tr></table>

  <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Jasper Listener - org.apache.catalina.core.JasperListener"><!--()--></a><a name="Jasper_Listener_-_org.apache.catalina.core.JasperListener"><strong>Jasper Listener - org.apache.catalina.core.JasperListener</strong></a></font></td></tr><tr><td><blockquote>

    <p>The <strong>Jasper Listener</strong> initializes the Jasper 2 JSP engine
    before any web applications that may use it are loaded. For more
    information on the Jasper 2 JSP engine see the
    <a href="../jasper-howto.html">Jasper How To</a>.</p>

    <p>This listener must only be nested within <a href="server.html">Server</a>
    elements.</p>

    <p>No additional attributes are supported by the <strong>Jasper Listener
    </strong>.</p>

  </blockquote></td></tr></table>

  <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Global Resources Lifecycle Listener - org.apache.catalina.mbeans.GlobalResourcesLifecycleListener"><!--()--></a><a name="Global_Resources_Lifecycle_Listener_-_org.apache.catalina.mbeans.GlobalResourcesLifecycleListener"><strong>Global Resources Lifecycle Listener - org.apache.catalina.mbeans.GlobalResourcesLifecycleListener</strong></a></font></td></tr><tr><td><blockquote>

    <p>The <strong>Global Resources Lifecycle Listener</strong> initializes the
    Global JNDI resources defined in server.xml as part of the <a href="globalresources.html">Global Resources</a> element. Without this
    listener, none of the Global Resources will be available.</p>

    <p>This listener must only be nested within <a href="server.html">Server</a>
    elements.</p>

    <p>No additional attributes are supported by the <strong>Global Resources
    Lifecycle Listener</strong>.</p>

  </blockquote></td></tr></table>

  <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="JRE Memory Leak Prevention Listener - org.apache.catalina.core.JreMemoryLeakPreventionListener"><!--()--></a><a name="JRE_Memory_Leak_Prevention_Listener_-_org.apache.catalina.core.JreMemoryLeakPreventionListener"><strong>JRE Memory Leak Prevention Listener - org.apache.catalina.core.JreMemoryLeakPreventionListener</strong></a></font></td></tr><tr><td><blockquote>

    <p>The <strong>JRE Memory Leak Prevention Listener</strong> provides
    work-arounds for known places where the Java Runtime environment uses
    the context class loader to load a singleton as this will cause a memory
    leak if a web application class loader happens to be the context class
    loader at the time. The work-around is to initialise these singletons when
    this listener starts as Tomcat's common class loader is the context class
    loader at that time. It also provides work-arounds for known issues that
    can result in locked JAR files.</p>

    <p>This listener must only be nested within <a href="server.html">Server</a>
    elements.</p>

    <p>The following additional attributes are supported by the <strong>JRE
    Memory Leak Prevention Listener</strong>:</p>

    <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code class="attributeName">appContextProtection</code></td><td align="left" valign="center">
        <p>Enables protection so that calls to
        <code>sun.awt.AppContext.getAppContext()</code> triggered by a web
        application do not result in a memory leak. Note that a call to this
        method will be triggered as part of the web application stop process
        when running on Java 6 and earlier. It is therefore strongly recommended
        that this protection is enabled when running on Java 6 and earlier. The
        default is <code>true</code> for Java 6 and earlier versions. The
        default is <code>false</code> for Java 7 and later versions.</p>
      </td></tr><tr><td align="left" valign="center"><code class="attributeName">AWTThreadProtection</code></td><td align="left" valign="center">
        <p>Enables protection so that calls to
        <code>java.awt.Toolkit.getDefaultToolkit()</code> triggered by a web
        application do not result in a memory leak.
        Defaults to <code>false</code> because an AWT thread is launched.</p>
      </td></tr><tr><td align="left" valign="center"><code class="attributeName">classesToInitialize</code></td><td align="left" valign="center">
        <p>List of comma-separated fully qualified class names to load and initialize
        during the startup of this Listener. This allows to pre-load classes that are
        known to provoke classloader leaks if they are loaded during a request
        processing. Non-JRE classes may be referenced, like
        <code>oracle.jdbc.driver.OracleTimeoutThreadPerVM</code>.
        The default value is empty, but specific JRE classes are loaded by other leak
        protection features managed by other attributes of this Listener.</p>
      </td></tr><tr><td align="left" valign="center"><code class="attributeName">driverManagerProtection</code></td><td align="left" valign="center">
        <p>The first use of <code>java.sql.DriverManager</code> will trigger the
        loading of JDBC Driver in the the current class loader. The web
        application level memory leak protection can take care of this in most
        cases but triggering the loading here has fewer side-effects. The
        default is <code>true</code>.</p>
      </td></tr><tr><td align="left" valign="center"><code class="attributeName">gcDaemonProtection</code></td><td align="left" valign="center">
        <p>Enables protection so that calls to
        <code>sun.misc.GC.requestLatency(long)</code> triggered by a web
        application do not result in a memory leak. Use of RMI is likely to
        trigger a call to this method. A side effect of enabling this protection
        is the creation of a thread named "GC Daemon". The protection uses
        reflection to access internal Sun classes and may generate errors on
        startup on non-Sun JVMs. The default is <code>true</code>.</p>
      </td></tr><tr><td align="left" valign="center"><code class="attributeName">java2DDisposerProtection</code></td><td align="left" valign="center">
        <p>Enables protection so that loading the
        <code>sun.java2d.Disposer</code> class by a web application does not
        result in a memory leak.
        Defaults to <code>false</code> because a thread is launched.</p>
      </td></tr><tr><td align="left" valign="center"><code class="attributeName">ldapPoolProtection</code></td><td align="left" valign="center">
        <p>Enables protection so that the PoolCleaner thread started by
        <code>com.sun.jndi.ldap.LdapPoolManager</code> does not result in a
        memory leak. The thread is started the first time the
        <code>LdapPoolManager</code> class is used if the system property
        <code>com.sun.jndi.ldap.connect.pool.timeout</code> is set to a value
        greater than 0. Without this protection, if a web application uses this
        class the PoolCleaner thread will be configured with the thread's
        context class loader set to the web application class loader which in
        turn will trigger a memory leak on reload. Defaults to
        <code>true</code>.</p>
      </td></tr><tr><td align="left" valign="center"><code class="attributeName">securityLoginConfigurationProtection</code></td><td align="left" valign="center">
        <p>Enables protection so that usage of the
        <code>javax.security.auth.login.Configuration</code> class by a web
        application does not provoke a memory leak. The first access of this
        class will trigger the initializer that will retain a static reference
        to the context class loader. The protection loads the class with the
        system class loader to ensure that the static initializer is not
        triggered by a web application. Defaults to <code>true</code>.</p>
      </td></tr><tr><td align="left" valign="center"><code class="attributeName">securityPolicyProtection</code></td><td align="left" valign="center">
        <p>Enables protection so that usage of the deprecated
        <code>javax.security.auth.Policy</code> class by a web application does not
        result in a memory leak. The first access of this class will trigger the
        static initializer that will retain a static reference to the context
        class loader. The protection calls the <code>getPolicy()</code> method
        of this class to ensure that the static initializer is not triggered by
        a web application. Defaults to <code>true</code>.</p>
      </td></tr><tr><td align="left" valign="center"><code class="attributeName">tokenPollerProtection</code></td><td align="left" valign="center">
        <p>Enables protection so that any token poller thread initialized by
        <code>sun.security.pkcs11.SunPKCS11.initToken()</code> does not
        result in a memory leak. The thread is started depending on various
        conditions as part of the initialization of the Java Cryptography
        Architecture. Without the protection this can happen during Webapp
        deployment when the MessageDigest for generating session IDs is
        initialized. As a result the thread has the Webapp class loader as its
        thread context class loader. Enabling the protection initializes JCA
        early during Tomcat startup. Defaults to <code>true</code>.</p>
      </td></tr><tr><td align="left" valign="center"><code class="attributeName">urlCacheProtection</code></td><td align="left" valign="center">
        <p>Enables protection so that reading resources from JAR files using
        <code>java.net.URLConnection</code>s does not result in the JAR file
        being locked. Note that enabling this protection disables caching by
        default for all resources obtained via
        <code>java.net.URLConnection</code>s. Caching may be re-enabled on a
        case by case basis as required. Defaults to <code>true</code>.</p>
      </td></tr><tr><td align="left" valign="center"><code class="attributeName">xmlParsingProtection</code></td><td align="left" valign="center">
        <p>Enables protection so that parsing XML files within a web application
        does not result in a memory leak. Note that memory profilers may not
        display the GC root associated with this leak making it particularly
        hard to diagnose. Defaults to <code>true</code>.</p>
      </td></tr></table>

  </blockquote></td></tr></table>

  <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Security Lifecycle Listener - org.apache.catalina.security.SecurityListener"><!--()--></a><a name="Security_Lifecycle_Listener_-_org.apache.catalina.security.SecurityListener"><strong>Security Lifecycle Listener - org.apache.catalina.security.SecurityListener</strong></a></font></td></tr><tr><td><blockquote>

    <p>The <strong>Security Lifecycle Listener</strong> performs a number of
    security checks when Tomcat starts and prevents Tomcat from starting if they
    fail. The listener is not enabled by default. To enabled it uncomment the
    listener in $CATALINA_BASE/conf/server.xml. If the operating system supports
    umask then the line in $CATALINA_HOME/bin/catalina.sh that obtains the umask
    also needs to be uncommented.</p>

    <p>This listener must only be nested within <a href="server.html">Server</a>
    elements.</p>

    <p>The following additional attributes are supported by the <strong>Security
    Lifecycle Listener</strong>:</p>

    <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code class="attributeName">checkedOsUsers</code></td><td align="left" valign="center">
        <p>A comma separated list of OS users that must not be used to start
        Tomcat. If not specified, the default value of <b>root</b> is used. To
        disable this check, set the attribute to the empty string. Usernames
        are checked in a case-insensitive manner.</p>
      </td></tr><tr><td align="left" valign="center"><code class="attributeName">minimumUmask</code></td><td align="left" valign="center">
        <p>The least rectrictive umask that must be configured before Tomcat
        will start. If not specified, the default value of <b>0007</b> is used.
        To disable this check, set the attribute to the empty string. The check
        is not performed on Windows platforms.</p>
      </td></tr></table>

  </blockquote></td></tr></table>

  <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="ThreadLocal Leak Prevention Listener - org.apache.catalina.core.ThreadLocalLeakPreventionListener"><!--()--></a><a name="ThreadLocal_Leak_Prevention_Listener_-_org.apache.catalina.core.ThreadLocalLeakPreventionListener"><strong>ThreadLocal Leak Prevention Listener - org.apache.catalina.core.ThreadLocalLeakPreventionListener</strong></a></font></td></tr><tr><td><blockquote>

    <p>The <strong>ThreadLocal Leak Prevention Listener</strong> triggers the
    renewal of threads in Executor pools when a
    <a href="context.html">Context</a> is being stopped to avoid thread-local
    related memory leaks. Active threads will be renewed one by one when they
    come back to the pool after executing their task.</p>

    <p>This listener must only be nested within <a href="server.html">Server</a>
    elements.</p>

    <p>No additional attributes are supported by the <strong>ThreadLocal Leak
    Prevention Listener</strong>.</p>

  </blockquote></td></tr></table>

  <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="UserConfig - org.apache.catalina.startup.UserConfig"><!--()--></a><a name="UserConfig_-_org.apache.catalina.startup.UserConfig"><strong>UserConfig - org.apache.catalina.startup.UserConfig</strong></a></font></td></tr><tr><td><blockquote>

    <p>The <strong>UserConfig</strong> provides feature of User Web Applications.
    User Web Applications map a request URI starting with a tilde character ("~")
    and a username to a directory (commonly named public_html) in that user's 
    home directory on the server.</p>

    <p>See the <a href="host.html#User_Web_Applications">User Web Applications</a>
    special feature on the <strong>Host</strong> element for more information.</p>

    <p>The following additional attributes are supported by the 
    <strong>UserConfig</strong>:</p>

    <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><code class="attributeName">directoryName</code></td><td align="left" valign="center">
        <p>The directory name to be searched for within each user home directory.
        The default is <code>public_html</code>.</p>
      </td></tr><tr><td align="left" valign="center"><code class="attributeName">userClass</code></td><td align="left" valign="center">
        <p>The class name of the user database class.
        There are currently two user database, the 
        <code>org.apache.catalina.startup.PasswdUserDatabase</code> is used on a
        Unix system that uses the /etc/passwd file to identify valid users.
        The <code>org.apache.catalina.startup.HomesUserDatabase</code> is used on 
        a server where /etc/passwd is not in use. HomesUserDatabase deploy all 
        directories found in a specified base directory.</p>
      </td></tr><tr><td align="left" valign="center"><code class="attributeName">homeBase</code></td><td align="left" valign="center">
        <p>The base directory containing user home directories.This is effective 
        only when <code>org.apache.catalina.startup.HomesUserDatabase</code> is 
        used.</p>
      </td></tr><tr><td align="left" valign="center"><code class="attributeName">allow</code></td><td align="left" valign="center">
        <p>A regular expression defining user who deployment is allowed. If this 
        attribute is specified, the user to deploy must match for this pattern.
        If this attribute is not specified, all users will be deployed unless the
        user matches a deny pattern.</p>
      </td></tr><tr><td align="left" valign="center"><code class="attributeName">deny</code></td><td align="left" valign="center">
        <p>A regular expression defining user who deployment is denied. If this
        attribute is specified, the user to deploy must not match for this
        pattern. If this attribute is not specified, deployment of user will be
        governed by a allow attribute.</p>
      </td></tr></table>

  </blockquote></td></tr></table>
  
</blockquote></td></tr></table><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="Additional Implementations"><!--()--></a><a name="Additional_Implementations"><strong>Additional Implementations</strong></a></font></td></tr><tr><td><blockquote>

  <table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#828DA6"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="JMX Remote Lifecycle Listener - org.apache.catalina.mbeans.JmxRemoteLifecycleListener"><!--()--></a><a name="JMX_Remote_Lifecycle_Listener_-_org.apache.catalina.mbeans.JmxRemoteLifecycleListener"><strong>JMX Remote Lifecycle Listener - org.apache.catalina.mbeans.JmxRemoteLifecycleListener</strong></a></font></td></tr><tr><td><blockquote>

    <p>This listener requires <code>catalina-jmx-remote.jar</code> to be placed
    in <code>$CATALINA_HOME/lib</code>. This jar may be found in the extras
    directory of the binary download area.</p>

    <p>The <strong>JMX Remote Lifecycle Listener</strong> fixes the ports used by
    the JMX/RMI Server making things much simpler if you need to connect
    jconsole or a similar tool to a remote Tomcat instance that is running
    behind a firewall. Only these ports are configured via the listener. The
    remainder of the configuration is via the standard system properties for
    configuring JMX. For further information on configuring JMX see
    <a href="http://docs.oracle.com/javase/6/docs/technotes/guides/management/agent.html">
    Monitoring and Management Using JMX</a> included with the Java SDK
    documentation.</p>

    <p>This listener must only be nested within a <a href="server.html">Server</a>
    element.</p>

    <p>The following additional attributes are supported by the <strong>JMX Remote
    Lifecycle Listener</strong>:</p>

    <table border="1" cellpadding="5"><tr><th width="15%" bgcolor="#023264"><font color="#ffffff">Attribute</font></th><th width="85%" bgcolor="#023264"><font color="#ffffff">Description</font></th></tr><tr><td align="left" valign="center"><strong><code class="attributeName">rmiRegistryPortPlatform</code></strong></td><td align="left" valign="center">
        <p>The port to be used by the JMX/RMI registry for the Platform MBeans.
        This replaces the use of the
        <code>com.sun.management.jmxremote.port</code> system property that
        should not be set when using this valve.</p>
      </td></tr><tr><td align="left" valign="center"><strong><code class="attributeName">rmiServerPortPlatform</code></strong></td><td align="left" valign="center">
        <p>The port to be used by the Platform JMX/RMI server.</p>
      </td></tr><tr><td align="left" valign="center"><code class="attributeName">rmiBindAddress</code></td><td align="left" valign="center">
        <p>The address of the interface to be used by JMX/RMI server. Setting
        this option to <code>true</code> is incompatible with setting the system
        property <code>com.sun.management.jmxremote.ssl</code> to
        <code>true</code>.</p>
      </td></tr><tr><td align="left" valign="center"><code class="attributeName">useLocalPorts</code></td><td align="left" valign="center">
        <p>Should any clients using these ports be forced to use local ports to
        connect to the the JMX/RMI server. This is useful when tunnelling
        connections over SSH or similar. Defaults to <code>false</code>.</p>
      </td></tr></table>

    <h3>Using file-based Authentication and Authorisation</h3>

    <p>If this listener was configured in server.xml as:
  <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
  &lt;Listener className="org.apache.catalina.mbeans.JmxRemoteLifecycleListener"
          rmiRegistryPortPlatform="10001" rmiServerPortPlatform="10002" /&gt;
  </pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
    with the following system properties set (e.g. in setenv.sh):
  <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
  -Dcom.sun.management.jmxremote.password.file=$CATALINA_BASE/conf/jmxremote.password
  -Dcom.sun.management.jmxremote.access.file=$CATALINA_BASE/conf/jmxremote.access
  -Dcom.sun.management.jmxremote.ssl=false
  </pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
    $CATALINA_BASE/conf/jmxremote.password containing:
  <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
  admin letmein
  </pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
    $CATALINA_BASE/conf/jmxremote.access containing:
  <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
  admin readwrite
  </pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
    then opening ports 10001 (RMI Registry) and 10002 (JMX/RMI Server) in your
    firewall would enable jconsole to connect to a Tomcat instance running
    behind a firewall using a connection string of the form:
  <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
  service:jmx:rmi://&lt;hostname&gt;:10002/jndi/rmi://&lt;hostname&gt;:10001/jmxrmi
  </pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
    with a user name of <code>admin</code> and a password of
    <code>letmein</code>.
    </p>

    <h3>Using JAAS</h3>

    <p>If we use the following system properties instead:
  <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
  -Dcom.sun.management.jmxremote.login.config=Tomcat
  -Djava.security.auth.login.config=$CATALINA_BASE/conf/login.config
  -Dcom.sun.management.jmxremote.access.file=$CATALINA_BASE/conf/jmxremote.access
  -Dcom.sun.management.jmxremote.ssl=false
  </pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
    $CATALINA_BASE/conf/login.config containing your choice of JAAS LoginModule implementation, for example:
  <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
  Tomcat { /* should match to the com.sun.management.jmxremote.login.config property */

    /* for illustration purposes only */
    com.sun.security.auth.module.LdapLoginModule REQUIRED
      userProvider="ldap://ldap-svr/ou=people,dc=example,dc=com"
      userFilter="(&amp;(uid={USERNAME})(objectClass=inetOrgPerson))"
      authzIdentity="admin"
      debug=true;
  };
  </pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
    $CATALINA_BASE/conf/jmxremote.access containing:
  <div align="left"><table cellspacing="4" cellpadding="0" border="0"><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#ffffff" height="1"><pre>
  admin readwrite
  </pre></td><td bgcolor="#023264" width="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr><tr><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td><td bgcolor="#023264" width="1" height="1"><img src="../images/void.gif" alt="" width="1" height="1" vspace="0" hspace="0" border="0"></td></tr></table></div>
    then we would need to provide LDAP credentials instead.
    </p>

    <p><strong>Note that the examples above do not use SSL. JMX access should
    be considered equivalent to administrative access and secured accordingly.
    </strong></p>

  </blockquote></td></tr></table>

</blockquote></td></tr></table></td></tr><tr class="noPrint"><td width="20%" valign="top" nowrap class="noPrint"></td><td width="80%" valign="top" align="left"><table border="0" cellspacing="0" cellpadding="2"><tr><td bgcolor="#525D76"><font color="#ffffff" face="arial,helvetica.sanserif"><a name="comments_section" id="comments_section"><strong>Comments</strong></a></font></td></tr><tr><td><blockquote><p class="notice"><strong>Notice: </strong>This comments section collects your suggestions
              on improving documentation for Apache Tomcat.<br><br>
              If you have trouble and need help, read
              <a href="http://tomcat.apache.org/findhelp.html">Find Help</a> page
              and ask your question on the tomcat-users
              <a href="http://tomcat.apache.org/lists.html">mailing list</a>.
              Do not ask such questions here. This is not a Q&amp;A section.<br><br>
              The Apache Comments System is explained <a href="/tomcat-7.0-doc/comments.html">here</a>.
              Comments may be removed by our moderators if they are either
              implemented or considered invalid/off-topic.</p><script type="text/javascript"><!--//--><![CDATA[//><!--
              var comments_shortname = 'tomcat';
              var comments_identifier = 'http://tomcat.apache.org/tomcat-7.0-doc/config/listeners.html';
              (function(w, d) {
                  if (w.location.hostname.toLowerCase() == "tomcat.apache.org") {
                      d.write('<div id="comments_thread"><\/div>');
                      var s = d.createElement('script');
                      s.type = 'text/javascript';
                      s.async = true;
                      s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
                      (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
                  }
                  else {
                      d.write('<div id="comments_thread"><strong>Comments are disabled for this page at the moment.<\/strong><\/div>');
                  }
              })(window, document);
              //--><!]]></script></blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr noshade size="1"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font color="#525D76" size="-1"><em>
        Copyright &copy; 1999-2013, Apache Software Foundation
        </em></font></div></td></tr></table></body></html>